Welcome to TokenHelp by The AG Group! The AG Group specializes in easy-to-use software tools for troubleshooting, optimizing, maintaining and expanding multivendor computer networks. While designed to take advantage of the intuitive, graphical interface of the Macintosh, our products can be used in virtually any heterogeneous networking environment.
This Reference Guide is intended to provide a more complete reference for TokenHelp users. Please review the Basic Guide for a capsulized overview of use of the application.
Installing TokenHelp
When copying the TokenHelp program to a hard disk, you must also copy the Hardware Interface file. The modules that operate the Token Ring hardware reside in the folder called “Hardware Interfaces.”
TIP: One recommended procedure is to keep TokenHelp and its related files on a floppy disk. This allows you to visit various locations of the network, insert the floppy disk, run TokenHelp and monitor the network from that location.
Hardware Requirements
TokenHelp runs on the following Macintosh computers:
All members of the Macintosh II Family, LCs, Quadras & Centris
You will need to be sure your Token Ring hardware is installed before you can capture packets with TokenHelp. The Macintosh must be equipped with at least one of the following supported Token interface cards:
DCA/Avatar LanWay 4/16 NuBus card
DCA/Avatar LanWay 4/16 LC card
DCA MacIrmaTrac card
Software
ToeknHelp requires Macintosh System 6.0.5 or later and is fully-compatible with System 7.X. It also requires AppleTalk version 54 or greater. TokenHelp uses its own software to interface with the Toekn Ring card and is not dependent upon vendor-supplied software drivers.
Memory
TokenHelp is normally configured to use 1MB of memory. However, it may be configured to run with more if you wish a larger capture buffer. The amount of memory you assign depends upon the number of packets you wish to capture and the RAM available. To change the memory size allocated, select the TokenHelp icon from the Finder and choose the "Get Info…" command in the File menu, then change the value for Application Memory Size (K).
TIP: To use memory more efficiently, it may not be necessary to capture every packet to understand what is happening on your network. That is why TokenHelp provides capture filtering.
Compatibility
TokenHelp is compatible with almost all applications except those which require the use of a network connection (including INITs). If AppleTalk network services run on the same Token Ring interface through which you intend to monitor your network, you should quit or disable those programs before running TokenHelp. Very often, AppleTalk network software will register itself as an AppleTalk client. TokenHelp must “unregister” all services to monitor the network, which may leave these other network programs in an undesirable or undefined state. If the network software is an application, exit the program. If it is a startup document, take it out of the System Folder and restart the Mac. Some programs can be disabled through the Chooser or through a related icon in the Control Panel or on the desktop. Another solution might be to configure these programs to use LocalTalk (Built-in) or EtherTalk, if possible, instead of TokenTalk.
If your Macintosh has 2 Token Ring cards installed, one card can be used for your normal network transactions and the other for TokenHelp. When 2 cards are installed, it is not necessary to quit or disable other networking services. It is only necessary to specify which card is to be used for your normal network services and which card is to be used for TokenHelp. Use "Select Adapter" under the File menu to specify which Token Ring card TokenHelp should use.
WARNING: If you are NOT running TokenHelp with two Token Ring cards, it is imperative to disable all network services on the Mac running TokenHelp, even if you will not be capturing the packet types used by those programs. TokenHelp puts the Token Ring card into “Promiscuous Mode,” and if these programs are running, they may get packets that were meant for other machines on the network. These programs may then try to process some of those packets and may even respond to them, confusing your attempt to analyze events and creating problems on the network.
Network Services
When you begin capturing or sending packets with TokenHelp, the program will ask if it is okay to disconnect from these services by presenting a warning message. If you choose "Disconnect Services", TokenHelp will prevent the use of AppleTalk or any other network services, which means that the network software on your Macintosh will no longer function properly. You may prevent the disconnection from taking place by clicking on the "Cancel" button. After choosing Cancel, you can quit TokenHelp and disconnect these network services through their own normal termination sequence. If you don’t want TokenHelp to give you this warning when you first begin a capture session, use the Chooser to make AppleTalk inactive by clicking on the "Inactive" button. Or, choose to run AppleTalk on LocalTalk by selecting "Built-in" (or by using an Ethernet card with EtherTalk installed), and selecting the appropriate icon in the Network Control Panel instead of TokenTalk. When you have finished running TokenHelp, if you previously had selected "Built-in" in the Network Control Panel, you may again select "TokenTalk" or, if you had made AppleTalk inactive in the Chooser, you should enable it again by clicking on the "Active" button. This will allow AppleTalk to use the Token Ring card in your Macintosh again.
Types of Filtering Available
If your network is very busy, you will quickly find that the number of packets TokenHelp captures in a short time can be quite large. Finding the packets in which you are interested can be difficult and time-consuming. For this reason, TokenHelp provides many pre-configured filters to eliminate the inconsequential or uninteresting packets from your packet capture. See the section below on Filtering.
Token Ring Addresses
Physical address - is the hardware-level address used by the Token Ring adapter to participate in the ring. Every device must have a unique physical address which is six bytes long and consists of 6 hexadecimal numbers usually separated by colon (:) characters, for example: 10:00:24:50:54:12. Typically, a hardware vendor obtains a block of physical address numbers from the IEEE and assigns a unique physical address to each adapter it builds. The vendor block of addresses is usually designated by 3 bytes that form the most significant bytes of the 6-byte physical Token Ring address. In this way, Token Ring physical addresses are generally distinct from one another, although some networks and protocols will override this built-in mechanism with one of their own. If a vendor allows you to override the built-in address, it usually provides this option as part of a Control Panel. However, TokenHelp ignores such configuration options and always uses the built-in address.
TIP: If you need to instruct TokenHelp to override the built-in Token Ring physical address, please contact The AG Group for instructions (see below).
Group node address - is a physical address specification that is recognized by more than one device on a ring. There are 3 types of group node addresses: broadcast, functional and group.
• Broadcast address - is also known as "All Stations" broadcast. Both of the following destination physical addresses are broadcast addresses:
C0:00:FF:FF:FF:FF
FF:FF:FF:FF:FF:FF
A packet with either one of the above destination addresses will be accepted by all the stations on a ring. While conceptually powerful, broadcast packets can be very expensive in terms of network resources because every station must spend the time and memory to receive and process a broadcast packet, even if that packet has no value or meaning for them.
• Functional address - is similar to a broadcast packet, except that only a specific, pre-defined class of nodes will receive the packet. A functional address is indicated by setting bit 0 of the second byte of the destination address to 0. Bit-significant decoding allows a station to recognize any or all of the 31 addresses that are assigned by Token Ring to network functions that require a well-known address.
• Group address - are similar to functional addresses, except that they are not generally
accepted by the Token Ring community, but instead are specifically user-defined. A group address is indicated by setting bit 0 of the second byte of the destination address to 1.
Logical address - is a network-layer address that is interpreted by a protocol handler. Logical addresses are used by networking software to allow packets to be independent of the physical connection of the network, i.e, to work with different network topologies and types of media. Each type of protocol has a different kind of logical address, for example:
An IP address consists of 4 decimal numbers separated by periods (e.g., 130.57.64.11)
An AppleTalk address consists of 2 decimals separated by a period (e.g., 200.4)
Some protocol types have logical broadcast addresses; for example:
The IP broadcast address typically uses 255 as its host portion (e.g., 130.57.255.255)
The AppleTalk broadcast address uses 255 as the node potion of the address (e.g., 200.255)
Depending on the type of protocol in a packet, a packet may also specify source and destination logical address information, either as extensions to the physical addresses or as alternatives to them. For example, if you were sending a packet to a different network, the higher-level, logical destination address might be for the computer on that network to which you are sending the packet, while the lower-level, physical Token Ring address might be the physical address of an internetwork device that bridges the 2 networks and is responsible for forwarding the packet to its ultimate destination.
Error Packets
TokenHelp recognizes and can capture 3 different types of errors: Isolating Errors, Non-isolating errors and Monitor Errors.
Isolating Errors
• Line Error - a packet or token was repeated by the ring station, either because the station detected a code violation within the packet or a Frame Check Sequence (FCS) error occurred.
• Internal - A ring station recognizes a recoverable internal error, e.g., a DMA bus error or DMA parity error, that doesn't exceed the abort thresholds specified in the initialization parameters. This can indicate a ring station in marginal operating condition.
• Burst - A burst error counter is contained in all Token Ring adapter configurations and is incremented when the adapter detects the absence of transitions for 5 half-bit times (a burst-five error).
• ARI/FCI - A ring station receives an Active Monitor Present (AMP) or Standby Monitor Present (SMP) MAC frame with the Address Recognition Indicator?frame Copied Indicator (ARI/FCI) bits equal to zero, or more than one SMP MAC frame with the ARI/FCI bits equal to zero, without receiving an intervening AMP MAC frame. the ARI/FCI bits are in the Fraame Status field which is transmitted after the end delimiter in every Token Ring packet. This condition indicates that the upstream neighbor is unable to set the ARI/FCI bits in a packet it has copied.
Non-isolating errors
Lost Frame - occurs when an adapter is in transmit mode and fails to receive the end of the frame it transmitted.
Receive Congestion - occurs when the adapter is in repeat mode and recognizes a packet addressed to it, but has no buffer space available for the packet.
Frame Copied - an adapter is in receive/repeat mode and recognizes a packet addressed to its specific address but finds the ARI bits not equal to zero. This indicates a possible line hit or duplicate address.
Frequency - A ring station detects a transmit/receive speed frequency error.
Token - The token error counter is active only in the active monitor station. It's incremented when the active monitor recognizes an error condition with the token protocol as follows:
• MONITOR_COUNT bit of a token with nonzero priority =1
• MONITOR_COUNT bit of a frame = 1
• No token or frame is received within a 10ms window
• Start delimiter/token sequence has a code violation in an area where they must not exist.
Monitor Errors
Monitor - the active monitor has received a Claim Token MAC control packet, indicating that another ring station detected a ring protocol error.
Duplicate Monitor - the active monitor has received a "Ring Purge" or "Active Monitor Present" control packet that it did not transmit, indicating the presence of another active monitor.
Duplicate Address - a ring station is in "Claim Token Transmit" mode and receives a "Claim Token" packet in which the source address equals the ring station's node address, but the Nearest Active Upstream Neighbor (NAUN) is different from the ring station's NAUN. This indicates that another ring station has the same node address.
Filtering
TokenHelp provides "filters" to eliminate the inconsequential or uninteresting packets from your review when you have a lot of network traffic. Use filters in the following ways:
• Capture filters tell TokenHelp which packets to capture. Enabled capture filters are applied to packets before they are placed in the capture buffer. This maximizes application memory by saving only specified packets, and allows you to focus on packets that are useful in analyzing or monitoring the network.
• Start triggers specify an event that triggers packet capture. A start trigger is a specification that tells TokenHelp to remain idle, reviewing but not capturing packets, until a specified event occurs. When the trigger event occurs, you can specify that EtherHelp begins capture (after applying all enabled filters), notifies you by playing an audible alarm or sending a message to your electronic paging unit, or performs a combination of these actions. Triggers are most useful when you suspect a network problem but have been unable to verify or reproduce it. By setting up a start trigger, you can wait until the event occurs to begin your capture activity. Or, if you know that the problem occurs at a particular time, you can set a time event to begin capturing packets during that time.
To enable capture filtering, follow these steps:
1. Choose "Filters..." in the Capture menu to open the Filters window.
2. At the top of the window, click the appropriate radio button to capture or not capture packets according to the filters.
3. Click the check box preceding the filter(s) you want to enable. When a filter is enabled, a check mark appears in the check box. To disable the filter, click once on the check mark.
NOTE: If multiple capture filters are enabled in the Filters window, the multiple filters are OR'd together, so any packet that meets all of the testing criteria of any one of the selected filters will be accepted.
Creating and Editing Filters
There are two ways to open the Filter Settings window, where filters are defined. You can double-click a filter name in the Filters window which will open the Filters Settings window, showing the settings for the selected filter or use the "Filters" menu, which is added to the menu bar when "Filtering..." is selected in the Capture menu. Instead of clicking in the box that precedes a filter's name, you can use the Filters menu to enable or disable a selected filter by choosing Add... in the Filters menu to open the Filters Settings window with no existing settings or name. When you open the Filter Settings window by choosing Add..., you will see an "Add More..." button between the OK and Cancel buttons. When you click "Add More...", the current filter is added to the list and all information is retained in the Filter Settings window. This is useful if you want to create additional filters with similar specifications.
Each filter can have up to 4 attributes, each of which can be enabled or disabled in a filter:
• Address attributes test each packet's source or destination address (or both). Address filtering is used to capture or ignore packets to or from particular devices.
• Protocol attributes test the protocol type in a packet. Protocol filtering is used to capture or ignore packets of a specified protocol type.
• Offset attributes test specific bytes or bits in each packet for a user-defined value. Offset filtering is used to specify exactly which packets you want to capture or ignore.
• MAC Control attributes test whether a packet is a MAC control frame or not.
When To Use Address Filters
Address filtering is very useful for focusing on packets between specific network devices. Using TokenHelp's ability to capture packets based upon embedded logical addresses, you may even monitor packets on your network sent to and received from machines on remote networks. If your network contains a link to other networks, you can monitor the network activity through the link by using an address filter to capture only packets containing the link device's address.
Using "Wild Cards" To Specify a Range of Addresses
You can use an asterisk (*) as a "wild card" in specifying physical or logical addresses. The (*) matches any number in the field in which it appears. For example, to refer to all stations using Nestar Token Ring adapters, you can specify the Nestar vendor ID followed by asterisks in the adapter-ID fields: "08:00:0A:*:*:*". To match any host on the class "C" IP network "200.10.10", you can specify the IP net number followed by an (*) in the host field: 200.10.10.*
Capturing All Packets From One Device
This example creates a filter that can be used to capture or ignore all packets being transmitted from a particular AppleTalk node:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu and the Filters Settings window will open.
3. Type a name (up to 23 characters) in the Filter: edit field at the top of the window.
4. Click the Address Filter check box.
5. Choose an address type from the Type pop-up menu. In this example, choose AppleTalk.
6. Click the Address-1 edit field, and enter a logical AppleTalk node address in that field.
NOTE: The node address you specify must be consistent with the address type you selected in the Type menu. If you had selected Token Ring instead of AppleTalk, you would need to enter the device's physical address.
7. Click next to "Any Address" in the Address-2 box.
8. Click next to "From Address-1 to Address-2". When you click in a "From Address..." check box, an arrow appears in the middle of the address filters area, to indicate the direction of the filter. Clicking on this arrow cycles through the possible directions (source, destination, or both) and is a shortcut for clicking the From Address... boxes.
To capture packets that are destined for a specific device, click next to "From Address-2 to Address-1" instead. You should see a left-pointing arrow appear in the middle of the address filter area. To capture packets sent to and received from a device to monitor traffic in and out of a specific address, click next to "From Address-2 to Address-1" and next to "From Address-1 to Address-2". A bidirectional arrow appears.
To monitor traffic in either direction (or in both directions) between two devices, turn off the "Any Address" button in the Address-2 box and enter the second specific address in the Address-2 field. Then click both check boxes: "From Address-1 to Address-2" and "From Address-2 to Address-1".
Protocol Filters
Protocol filtering allows you to capture only packets of a certain protocol type.
Using "Wild Cards" to Specify Protocols
You can use the (*) character as a "wild card" in specifying protocol types. The (*) matches any number in the field in which it appears. For example, the DECnet protocols use the following 2-byte Ethernet protocol specifications:
60-02 DEC_MOP
60-03 DEC_Transport
60-04 DEC_LAT
60-06 DEC_UPT
60-07 DEC_Control
You can represent the entire DECnet suite by using the wild card "*-*-*-60-*" or "00-00-00-60-*".
Creating Protocol Filters
There are two ways to specify a protocol type in a filter: by protocol name or by the hex representation of the LSAP or SNAP values for the protocol. The following example creates a filter that can be used to capture or ignore all XNS packets:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu.
3. Type a name in the Filter: edit field.
4. Click the Protocol Filter check box.
5. Choose the appropriate specification from the protocol Type pop-up menu. XNS uses the 5-byte SNAP protocol discriminator, so choose the 802.2 SNAP ID type.
6. Type the 5-byte protocol discriminator for XNS in the Protocol: field.
7. Click OK and close the window, or click Add More... if you wish to define additional filters.
Offset Filters
Offset filtering allows you to pinpoint packets by capturing a packet only if it meets very specific criteria based upon the value of certain bits or bytes. An offset is the byte number where certain information or data occurs in a packet.
For most uses of TokenHelp, address and protocol filtering are sufficient to specify the network activity you wish to view. However, you may occasionally wish to filter packets based on more rigorous criteria. For example, you may want to capture only packets that have a socket number of 6, or you may want to collect only ICMP packets with an Unreachable Destination error number.
Each offset filter can test up to 16 bytes in a packet for a specified value at each location. If all of the "active" tests in a filter pass (and the filter is enabled), the packet is captured.
NOTE: Use offset filters with an address filter to fine-tune the packets you wish to view. For example, you can use an addess filter to specify a particular AppleTalk router, and then set an offset filter that specifies the standard offset for NBP-Long packets with a further offset limiting packet capture to only those packets being routed into a particular network. With offset filters, you can specify completely the exact packets you wish to view.
Offset Filters At Work
This section describes the "test" values you can enter in the Offset Filter window to pinpoint the byte and which bits within that byte you want to use in the filter. To open the Offset Filter window, follow these steps:
1. Select Filtering... from the Capture menu.
2. Select Add... from the Filters menu.
3. Click the Offset Filter button to open the Offset Filter window. In this window, there are 16 rows, each of which can be used to specify a test for one location in a packet. Each row has four fields and an enable switch. The four fields are as follows:
• Name - The text in this field (up to 23 characters) is optional and does not affect the filtering of packets. It is used to help you remeber the meaning of the specified values.
• Offset - The number in this field indicates the location of a byte in the packet. If you enter 0, the first byte of a packet will be examined, 1 examines the second byte and so forth. You can enter the number in hex ($0 to $FF) or decimal (0-255). However, the number is always stored in decimal.
• Mask - The number in this field is used to isolate the bits inside of the byte specified by the Offset field. This value is AND'ed with the value present in the byte and the result is examined. If you enter $FF, TokenHelp examines all of the bits in the byte, while a mask of 80 causes TokenHelp to examine only the most significant bit.
• Value - The number in this field is the "constant" that TokenHelp compares to the value it obtains by applying the Mask to the Offset byte. If the value specified here matches the value in the specified byte (or bits) in a packet, the test passes.
Creating An Example Offset Filter
This example creates an offset filter to capture AppleTalk packets of a specific datagram length. To create the filter, you must first know that the "datagram length" field in AppleTalk packets is a 10-bit field that begins in the 22nd byte of a packet with the 2 least significant bits and continues as the eight bits in the following byte. So, this filter will need to include tests for both the 22nd and 23rd byte of each packet. This type of information can be found in "Inside AppleTalk, Second Edition".
Say that you want to capture all AppleTalk packets with a datagram length of 420 (0x1A4). The total value to test for is 420 (0x1A4). First, make sure that existing filters will not prevent these packets from being captured; in fact, you might want to limit capture to just AppleTalk packets. Then, follow these steps:
1. Select "Filtering..." from the Capture menu.
2. Select "Add..." from the Filters menu.
3. Assign a name to the filter, e.g., "DDP Long".
4. Click the Offset Filters button to open the Offset Filter window.
5. Click the first check box to enable this test, and then type a name in the Name field to remind you of the function of this test; e.g.: "DDP len-hi".
6. Specify the byte you want to examine, in this case byte 22, by typing a hex value in the Offset field: "0x15". Hex 15 is decimal 21, which represents the 22nd byte of the packet.
7. Specify the bits within this byte, in this case the 2 least significant bits, by typing a hex value in the Mask field: "0x3".
8. Specify the constant value "1" in the Value field: 0x1. The total value to test for is 420 (0x1A4), so the value for byte 22 should be 1.
9. Click the second check box to enable this test, and then type a name in the Name field to remind you of the function of this test, e.g.: "DDP len-low".
10. Specify the byte you want to examine, in this case byte 23, by typing a hex value in the Offset field: "0x16". Hex 16 is decimal 22, which represents the 23rd byte of the packet.
11. Specify the bits within this byte, in this case all eight bits, by typing a hex value in the Mask field: "0xff".
12. Specify the constant value "A4" in the Value field: "Oxa4". The total value to test for is 420 (Ox1A4), so the value for byte 23 should be A4.
13. Click OK.
14. In the Filter Settings window, click the Offset Filter box to enable this filter.
15. Type a name in the Filter: edit field at the top of the window.
16. Click OK to exit, or click "Add More..." if you want to create new filters.
MAC Control Filters
MAC Control filtering allows you to capture only data packets (non-MAC control frames) or MAC control frames.
When to Use MAC Control filtering
MAC Control filtering is most useful when you want to limit the number of packets captured by ignoring all MAC control frames. Or, if you want to focus on the information in MAC control frames, you could use this type of filter to ignore all packets other than control packets.
Triggering
You may wish to keep TokenHelp idle or in a holding pattern (continuously capturing) until a specific event occurs on your network. These events can be one or more of the following:
• an address or protocol type appears in a packet on the network
• a user-defined value in some bits or bytes appears in a packet on the network
• an error packet is received
• the Macintosh system clock reaches a user-defined time
When one of these events occur, TokenHelp can begin capturing packets. The automatic start of data capture based on network events is called Triggering.
Trigger Start
To configure TokenHelp to recognize a trigger event, you must specify the trigger parameters and then use a check box to indicate if the trigger is enabled or disabled. Each enabled trigger event is independent of the others that have been enabled, i. e., capture is started if any of the enabled trigger events occur.
• The “Time” trigger event causes packet capture to start at a specified time.
• The “Filter” trigger causes capture to start when a checked filter is passed.
• The “Start Capture” check box is used to specify that capture of all packets, according to the filters, should begin when any of the trigger event conditions is met.
• The “Notify” box is used to cause an audible alarm at the occurrence of the trigger event.
NOTE: If the “Start Capture” check box is not checked, but the “Notify” check box is checked, only packets which cause the trigger event will be captured.
When Start Triggering is enabled, a small diamond appears next to the "Start Trigger..." item in the Capture menu and the "Start Capture" button turns into a "Start Trigger" button. By clicking on this button, or by using the "Start Trigger" item in the Capture menu, TokenHelp begins reviewing but NOT capturing packets until the trigger criteria is met. Once clicked, TokenHelp will begin monitoring packets on the network and will continue to do so until one of the packets matches an enabled trigger criteria. If the “Notify upon trigger event” check box is checked, and the “Start capture upon trigger event” check box is not checked, the packet causing the trigger will be captured, and TokenHelp will continue waiting for more trigger matches.
After triggering is activated, the button will be renamed to Abort Trigger. When the trigger event occurs, capture begins and the button reverts to its normal label of Stop Capture.
Saving and Restoring Settings
The settings file contains all the information required to set up filters and triggers. After you have set up your filters and triggers, Tokenhelp will remember the settings each time it starts up. However, you can also save these settings to a separate file so that they can be selectively restored as required. In fact, you may have received a TokenHelp settings file from your vendor in order to streamline capture and subsequent diagnosis. A settings file is useful when different configurations of settings are repeatedly used for things like diagnostics and testing. To save and restore configuration settings, use the "Save Settings" and "Load Settings..." items from the File menu.
If you are intrigued by TokenHelp and would like to learn more about our other network management tools, please contact us. Our family of products now includes:
